Microsoft Codeview and Utilities
================================

CHAPTER 2 ___ THE CODEVIEW DISPLAY

The Microsoft CodeView debugger screen display can appear in two different
modes - window and sequential.  Either mode provides a useful debugging
environment, but the window mode is the more powerful and convenient of the
two.  The CodeView debugger accepts either window commands or dialog commands.
Dialog commands are entered as command lines following the CodeView prompt (>)
in sequential mode.  They are discussed in Chapter 3, "Using Dialog Commands."

You will probably want to use window mode, if you have the hardware to support
it.  In window mode, the pull-down menus, function keys, and mouse support
offer fast access to the most common commands.  Different aspects of the
program and debugging environment can be seen in different windows simul-
taneously.  Window mode is described in Section 2.1.

Sequential mode is similar to the display mode of the CodeView debugger's
predecessors, the  Microsoft Symbolic Debug Utility (SYMDEB) and the DOS DEBUG
utility.  This mode is required if you do not have an IBM-compatible computer,
and it is sometimes useful when redirecting command input or output.
Sequential mode is described in Section 2.2.

2.1  Using Window Mode

The elements of the CodeView display marked in Figure 2.1 below include the
following:

1.	The display window shows the program being debugged.  It can contain
	source code (as in the example), assembly language instructions, or
	any specified text file.

2.	The current location line (the next line the program will execute) is
	displayed in reverse video or in a different color.  This line may not
	always be visible, because you can scroll to earlier or later parts of
	the program.

3.	Lines containing previously set breakpoints are shown in high-
	intensity text.

4.	The dialog window is where you enter dialog commands.  These are the
	commands with optional arguments that you can enter at the CodeView
	prompt (>).  You can scroll up or down in this window to view previous
	dialog commands and command output.

5.	The cursor is a thin, blinking line that shows the location at which
	you can enter commands from the keyboard.  You can move the cursor up
	and down, and place it in either the dialog or display window.

6.	The display/dialog separator line divides the dialog window from the
	display window.


7.	The register window shows the current status of processor registers
	and flags.  This is an optional window thaat can be opened or closed
	with one keystroke or with the mouse.  If the 386 option is on, a much
	wider register window is displayed, with 32 bit registers.  The regis-
	ter window also displays the effective address at the bottom of the
	window; the effective address shows the actual location of an operand
	in physical memory.  It is useful when debugging in assembly mode.

8.	The scroll bars are the vertical bars on the right side of the screen
	Each scroll bar has an up arrow and a down arrow that you can use to
	scroll through the display with a mouse.

9.	The optional watch window shows the current status of specified var-
	iables or expressions.  It appears automatically whenever you create
	watch statements.

10.	The menu bar shows titles of menus and commands that you can activate
	with the keyboard or the mouse.  "Trace" and "Go" represent commands;
	the others are all menus.

11.	Menus can be opened by specifying the appropriate title on the menu
	bar.  On the sample screen, the Watch menu has been opened.

12.	The menu "highlight" is a reverse-video or colored strip indicating
	the current selection in a menu.  You can move the highlight up or
	down to change the current selection.

13.	The mouse pointer indicates the current position of the mouse.  It is
	shown only if you have a mouse installed on your system.

14.	Dialog boxes (not shown) appear in the center of the screen when you
	choose a menu selection that requires a response.  The box prompts you
	for a response and disappears when you enter your answer.

15.	Message boxes (not shown) appear in the center of the screen to
	display errors or other messages.

The screen elements are described in more detail in the rest of this chapter.

2.1.1  Executing Window Commands with the Keyboard

The most common CodeView debugging commands and all the commands for managing
the CodeView display are available with window commands.  Window commands are
one-keystroke commands that can be entered with function keys, CONTROL-key
combinations, ALT-key combinations, or the direction keys on the numeric
keypad.

Most window commands can also be entered with a mouse, as described in Section
2.1.2, "Changing the Screen with the Mouse."  The window commands available
from the keyboard are described by category in Sections 2.1.1.1-2.1.1.4 below.



2.1.1.1  Moving the Cursor with Keyboard Commands

The following keys move the cursor or scroll text up or down in the display or
dialog window.

Key		Function
------------------------
F6		Moves the cursor between the display and dialog windows.
		If the cursor is in the dialog window when you press F6, it
		will move to its previous position in the display window.  If
		the cursor is in the display window, it will move to its
		previous position in the dialog window.

CONTROL+G	Makes the size of the dialog or display window grow.

		This works for whichever window the cursor is in.  If the cur-
		sor is in the display window, then the display/dialog separator
		line will move down one line.  If the cursor is in the dialog
		window, then the separator line will move up one line.

CONTROL+T	Makes the size of the dialog or display window smaller.

		This works for whichever window the cursor is in.  If the cur-
		sor is in the display window, then the display/dialog separ-
		ator line will move up one line.  If the cursor is in the
		dialog window, then the separator line will move down one line.

UP ARROW	Moves the cursor up one line in either the display or dialog
		window.

DOWN ARROW	Moves the cursor down one line in either the display or dialog
		window.

PGUP		Scrolls up one page.

		If the cursor is in the display window, the source lines or
		assembly language instructions scroll up.  If the cursor is in
		the dialog window, the buffer of commands entered during the
		session scrolls up.  The cursor remains at its current 
		position in the window.  The length of a page is the current
		number of lines in the window.

PGDN		Scrolls down one page.

		If the cursor is in the display window, the source lines or
		assembly language instructions scroll down.  If the cursor is
		in the dialog window, the buffer of commands entered during
		the session scrolls down.  The cursor remains at its current
		position in the window.  The length of a page is the current
		number of lines in the window.

HOME		Scrolls to the top of the file or command buffer.

		If the cursor is in the display window, the text scrolls to
		the start of the source file or program instructions.  If the
		cursor is in the dialog window, the commands scroll to the top
		of the command buffer.  The top of the command buffer may be
		blank if you have not yet entered enough commands to fill the
		buffer.  The cursor remains at its current position in the
		window.

END		Scrolls to the bottom of the file or command buffer.

		If the cursor is in the display window, the text scrolls to
		the end of the source file or program instructions.  If the
		cursor is in the dialog window, the commands scroll to the
		bottom of the command buffer, and the cursor moves to the
		CodeView prompt (>) at the end of the buffer.

2.1.1.2  Changing the Screen with Keyboard Commands

The following keys change the screen or switch to a different screen.

Key		Function
-----------------------
F1		Displays initial on-line help screen.

		The help system is discussed in Section 2.1.4.  You can also
		take advantage of the help system by using the Help menu, as
		mentioned in Section 2.1.3.9.

F2		Toggles the register window.

		The window disappears if present, or appears if absent.  You
		can also toggle the register window with the Register
		selection from the View menu, as described in Section 2.1.3.2.

F3		Switches between source, mixed, and assembly modes.

		Source mode shows source code in the display window, whereas
		assembly mode shows assembly language instructions.  Mixed
		mode shows both.  You can also change modes with the Source,
		Mixed, and Assembly selections from the View menu, as
		described in Section 2.1.3.2.

F4		Switches to the output screen.

		The output screen shows the output, if any, from your program.
Press any key to return to the CodeView screen.

2.1.1.3  Controlling Program Execution with Keyboard Commands

The following keys set and clear breakpoints, trace through your program, or
execute to a breakpoint.

Key		Function
-----------------------
F5		Execute to the next breakpoint or to the end of the program if
		no breakpoint is encountered.
		This keyboard command corresponds to the Go dialog command
		when it is given without a destination breakpoint argument.

F7		Sets a temporary breakpoint on the line with the cursor, and
		executes to that line (or to a previously set breakpoint or
		the end of the program if either is encountered before the
		temporary breakpoint).

		In source mode, if the line does not correspond to code (for
		example, data declarations or comment lines), the CodeView
		debugger sounds a warning and ignores the command.  This
		window command corresponds to the Go dialog command when it is
		given with a destination breakpoint.

F8		Executes a Trace command.

		The CodeView debugger executes the next source line in source
		mode or the next instruction in assembly mode.  If the source
		line or instruction contains a call to a routine or interrupt
		the debugger starts tracing through the call (enters the call
		and is ready to execute the first source line or instruction).
		This command will not trace into DOS function calls.

F9		Sets or clears a breakpoint on the line with the cursor.

		If the line does not currently have a breakpoint, one is set
		on that line.  If the line already has a breakpoint, the
		breakpoint is cleared.  If the cursor is in the dialog window,
		the CodeView debugger sounds a warning and ignores the
		command.  This window command corresponds to the Breakpoint
		Set and Breakpoint Clear dialog commands.

F10		Executes the Program Step command.
		The CodeView debugger executes the next source line in source
		mode, or the next instruction in assembly mode.  If the source
		line ir instruction contains a call to a routine or interrupt,
		the debugger steps over the entire call (executes it to the
		return) and is ready to execute the line or instruction after
		the call.
---------
Important
---------
You can usually interrupt program execution by pressing either
CONTROL+BREAK or CONTROL+C.  These key combinations can be used to exit
endless loops or to interrupt loops that are slowed by the Watchpoint or
Tracepoint commands (see Chapter 8, "Managing Watch Statements"). CONTROL+
BREAK or CONTROL+C may not work if your program has a special use for one
or both of these key combinations.  If you have an IBM Personal Computer AT
(or an AT-compatible), you can use the SYSTEM-REQUEST key to interrupt
execution regardless of your program's use of CONTROL+BREAK and CONTROL+C.
==========

2.1.1.4  Selecting from Menus with the Keyboard

This section discusses how to make selections from menus with the keyboard. The
effects of the selections are discussed in Section 2.1.3, "Using Menu
Selections."

The menu bar at the top of the screen has eleven titles: File, View, Search,
Run, Watch, Options, Language, Calls, Help, Trace, and Go.  The first nine
titles are menus, and the last two are commands.  The Trace and Go titles are
provided primarily for mouse users.

The four steps for opening a menu and making a selection are described below:

1. To open a menu, press the ALT key and the mnemonic (the first letter)
of the menu title.  This can be accomplished either by pressing the
ALT key first, releasing the key, and pressing the letter; or you can
hold down the ALT key and then press the letter.  For example, press
ALT+S to open the Search menu.  The menu title is highlighted, and a
menu box listing the selections pops up below the title.  You can type
either an uppercase or lowercase letter to open any of the menus.

2. There are two ways to make a selection from an open menu:

a. Press the DOWN ARROW key on the numeric keypad to move down the
menu.  The highlight will follow your movement.  When the item you
want is highlighted, press the ENTER key to execute the command.
For example, press the DOWN ARROW once to select Find from the
Search menu.

You can also press the UP ARROW key to move up the menu.  If you
move off the top or bottom of the menu, the highlight wraps around
to the other end of the menu.

b. Press the key corresponding to the menu-selection mnemonic.  The
mnemonic is simply a single letter that represents the selection.
In color displays, this letter is in red; in black and white dis-
plays, this letter is in bold.  In most cases, but not all, the
letter is simply the first letter of the name of the selection.
You can type either an uppercase or lowercase letter for the same
selection.

3. After a selection is made from the menu, one of three things will
happen:
a. For most menu selections, the choice is executed immediately.
b. The items on the View, Options, and Language menus have small
double arrows next to them if the option is on, or no arrows if the
option is off.  Choosing the item toggles the option.  The status
of the arrows will be reversed the next time an option is chosen.
c. Some items require a response.  In this case, there is another step
in the menu-selection process.

4. If the item you select requires a response, a dialog box opens when
you select a menu item.  Type your response to the prompt in the box
and press the ENTER key.  For example, the Find dialog box asks you to
enter a regular expression (see Appendix A for a complete explanation
of regular expressions).  If your response is valid, the command will
be executed.  If you enter an invalid response, a message box will appear
telling you the problem and asking you to press a key.  Press any key to
make the message box disappear.

At any point during the process of selecting a menu item, you can press the
ESCAPE key to cancel the menu.  While a menu is open, you can press the LEFT
ARROW or RIGHT ARROW key to move from one menu to an adjacent menu, or to one
of the command titles on the menu bar.  Pressing ENTER without entering any
characters in response to a message box will also cancel the menu.

2.1.2  Executing Window Commands with the Mouse

The CodeView debugger is designed to work with the Microsoft Mouse (it also
works with some compatible pointing devices).  By moving the mouse on a flat
surface, you can move the mouse pointer in a corresponding direction on the
screen.  The following terms refer to the way you select items or execute
commands with the mouse.

Term	Definition
--------------------
Point	Move the mouse until the mouse pointer rests on the item you want
	to select.

Click	Quickly press and release a mouse button while pointing at an item
	you want to select.

Drag	Press a mouse button while on a selected item, then hold the button
	down while moving the mouse.  The item moves in the direction of
	the mouse movement.  When the item you are moving is where you want
	it, release the button; the item will stay at that place.

The CodeView debugger uses two mouse buttons.  The terms "click right," "click
left," "click both," and "click either" are sometimes used to designate which
buttons to use.  When dragging, either button can be used.

2.1.2.1  Changing the Screen with the Mouse

You can change various aspects of the screen display by pointing to one of the
following elements and then either clicking or dragging.

Item		Action
--------------------------
Double line	Drag the separator line up to increase the size of the
separating	the dialog window while decreasing the size of the
display		display window, or drag the line down to increase the
and dialog	size of the display window while decreasing the size
windows		of the dialog window.  You can eliminate either
		completely by dragging the line all the way up or down
		(providing the cursor is not in the window you want to
		eliminate).

UP ARROW	Point and click left button on one of the four arrows
or DOWN		on the scroll bars to scroll up or down.  If you are
ARROW on	in the display window, source code scrolls up or down.
the scroll	If you are in the dialog window, the buffer containing
		dialog commands entered dukring the session scrolls up
		or down.

		Click left button to scroll up or down just one line
		at a time.  Press left button and hold it down in
		order to scroll continuously.  Continuous scrolling is
		easier to use when you want to scroll more than a
		couple of lines.  The scrolling stops as soon as you
		release the mouse button.

Scroll bar	Each scroll bar has an "elevator," which is a high-
elevator	lighted rectangle on the bar that can be moved up or 
		down with the mouse.  In the display window, the ele-
		vator indicates your relative position in the source
		file; if you are in mixed or assembly mode, the ele-
		vator indicates your position in the executable file
		relative to the instructions that caorrespond to the
		source file.  You can move quickly through the source
		file by dragging the display window elevator up or
		down.

		In the dialog window, the position of the elevator
		does not have any significance.

		To move up one page (either in the display or dialog
		window), click the scroll bar anywhere above the ele-
		vator.  To move down a page, click the scroll bar
		anywhere below the elevator.

2.1.2.2  Controlling Program Execution with the Mouse

By clicking the following mouse items, you can set and clear breakpoints,
trace through your program, execute to a breakpoint, or change flag bits.

Item			Action
------------------------------
Source line or		Point and click on a source line in source mode or on
instruction		an instruction in assembly mode to take one of the
			following actions:

	Button		Result
	-------------------
	Click left	If the line under the mouse cursor does not have a
			breakpoint, one is set there.  If the line already 
			has a breakpoint, the breakpoint is removed.  Lines
			with breakpoints are shown in high-intensity text.

	Click right	A temporary breakpoint is set on the line, and the
			CodeView debugger executes until it reaches the line
			(or until it reaches a previously set breakpoint or
			the end of the program if either is encountered before
			the temporary breakpoint).
		If you click on a line that does not correspond to code (for
		example, a declaration or comment), the CodeView debugger will
		sound a warning and ignore the command.

"Trace" on menu bar

	Point and click to trace the next instruction.  The kind of trace
	is determined by the button clicked:

	Button		Result
	---------------------
	Click left	The Trace command is executed.  The CodeView debugger
			executes the next source line in source mode or the
			next instruction in assembly mode.  If the source line
			or instruction contains a call to a routine or
			interrupt, the debugger starts tracing through the
			call (it enters the call and is ready to execute the
			first source line or instruction).  This command will
			not trace into DOS function calls.

	Click right	The Program Step command is executed.  The debugger
			executes the next source line in source mode, or the
			next instruction in assembly mode.  If the source line
			or instruction contains a call to a routine or inter-
			rupt, the CodeView debugger steps over the entire call
			(it executes the call to the returnf) and is ready to  
			execute the line or instruction after the call.
		These two commands are different only if the current location
		is the start of a procedure, interrupt, or call.

"Go" on menu bar

		Point and click either button to execute to the next break-
		point, or to the end of the program if no breakpoints are        
		encountered.

Flag in register window

		Point to a flag name and click either button to reverse the
		flag.  If the flag bit is set, it will be cleared; if the flag
		bit is cleared, it will be set.  The flag name is changed on
		the screen to match the new status.  If you are using color
		mode, the color of the flag mnemonic will also change.  This
		command can only be used when the register window is open.
		Use the command with caution, since changing flag bits can
		change program execution at the lowest level.
---------
Important
---------
You can usually interrupt program execution by pressing either CONTROL+
BREAK or CONTROL+C.  See the note in Section 2.1.1.3, "Controlling Program
Execution with Keyboard Commands," for more information.
----

2.1.2.3  Selecting from Menus with the Mouse

This section discusses how to make selections from menus with the mouse.  The
effect of each selection is discussed in Section 2.1.3, "Using Menu
Selections."

The menu bar at the top of the screen has nine titles: File, View, Search,
Run, Watch, Options, Language, Calls, Help, Trace, and Go.  The first nine
titles are menus, and the last two are commands that you can execute by
clicking with the mouse.  The five steps for opening a menu and making a
selection are described below:

1. To open a menu, point to the title of the menu you want to select.
For example, move the pointer onto File on the menu bar if you want to
open the File menu.

2. With the mouse pointer on the title, press and hold down either mouse
button.  The selected title is highlighted and a menu box with a list
of selections pops up below the title.  For example, if you  point to
Search and press a button, the Search menu pops up.

3. With the button held down, move the mouse toward you.  The highlight
follows the mouse movement.  You can move the highlight up or down in
the menu box.  For example, to select Find from the Search menu, move
the highlight down the menu to Find.
If you move off the box, the highlight will disappear.  However, as
long as you do not release the button, you can move the pointer back
onto the menu to make the highlight reappear.

4. When the selection you want is highlighted, release the mouse button.
For example, release the button with the highlight on Find.
When you release the button, the menu selection is executed.  One of
three things will happen:

a. For most menu selections, the choice is executed immediately.

b. The items on the View, Options, and Language menus have small
double arrows next to them if the option is on, or no arrows if
the option is off.  Choosing the item toggles the option.  The
status of the arrows on a chosen item will appear reversed the
next time you open the menu.

c. Some items require a response.  In this case, there is another
step in the menu selection process.

5. If the item you select requires a response, a dialog box with a prompt
appears. Type your response and press the ENTER key or a mouse button.
For example, if you selected Find, the prompt will ask you to enter a
regular expression (see Section 2.1.3.3, "The Search Menu," or
Appendix A, "Regular Expressions," for an explanation of regular
expressions).

If your response is valid, the command will be executed.  If you enter     
an invalid response in the dialog box, a message box will appear
telling you the problem and asking you to press a key.  Press any key
or click a mouse button to make the message box disappear.
Also, if you press ENTER without entering any characters, the message
box will disappear.

There are several shortcuts you can take when selecting menu items with the
mouse.  If you change your mind and decide not to select an item from a menu,
just move off the menu and release the mouse button--the menu pointer directly
from any point on the current menu to the title of the new menu.


.end of 1st half.